The CICA Windows Explosion!/The CICA Windows Explosion! - Disc 2.iso/demo/wemdemo4.zip/INFO/W3.2

GNU Info File | 1994-09-21 | 48KB | 831 lines

This is Info file ../info/w3, produced by Makeinfo-1.56 from the input
file w3.txi.
   This file documents the Emacs-w3 World Wide Web browser.
   Copyright (C) 1993, 1994 William M. Perry
   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
File: w3,  Node: Personal Annotations,  Prev: Group Annotations,  Up: Annotations
Personal Annotations
--------------------
   If you do not want to share your musings about a particular document
with the entire network, you can add a personal annotation that only you
can see.  Personal annotations are stored in a subdirectory in the users
account on the local disk, with a log file that contains information
about what URLs have been annotated and which files contain the
annotations.
   Emacs-w3 looks in the directory specified by
`w3-personal-annotation-directory' (defaults to
`~/.mosaic-personal-annotations').  Any personal annotations for a
document are automatically appended when it is retrieved.
   To add a new personal annotation, type `M-x
w3-add-personal-annotation'.  This puts you in a new buffer, in the mode
specified by `w3-annotation-mode'.  This defaults to `html-mode'.  If
this variable is `nil', or it points to an undefined function, then
`default-major-mode' is consulted.
   A minor mode redefines `C-c C-c' to complete the annotation and
store it on your local disk.
   To delete a personal annotation, you must be reading it.  Once
reading the annotation, type `M-x w3-delete-personal-annotation'.  It
deletes the file containing the annotation, and any references to it in
your log file.
   I do not currently support editing personal annotations.
File: w3,  Node: Controlling Formatting,  Next: General Formatting,  Prev: Top,  Up: Top
Controlling Formatting
**********************
   How Emacs-w3 formats a document is very customizable.  How a
document is displayed depends on whether the user is on a terminal
capable of graphics and a few variables.
   The following sections describe in more detail how to change the
formatting of a document.
* Menu:
* General Formatting::                 Changing general things about a
                                       document.
* Character based terminals::          Changing how a document is
                                       displayed on a non-graphics
                                       terminal (vt100, etc.) or if
                                       `w3-delimit-emphasis' is `t'.
* Smart terminals::                    Getting highlighting of links, etc.
                                       on not-quite-so-dumb terminals (vt100s
                                       and comparable machines)
* Graphics workstations::              Changing how a document is
                                       displayed on a graphics terminal
                                       (Xwindows, Windows, NeXTstep,
                                       OS/2, etc.)
* Inlined images::                     How to specify how Emacs-w3
                                       handles inlined images/mpegs.
File: w3,  Node: General Formatting,  Next: Character based terminals,  Prev: Controlling Formatting,  Up: Controlling Formatting
General formatting conventions
==============================
                          -------------------
                        Setting the fill column
                          -------------------
   Each time a document is parsed, the `fill-column' is recalculated
using `window-width' and `w3-right-border'.  `w3-right-border' is an
integer specifying how much room at the right edge of the screen to
leave blank.  The `fill-column' is set to `(- (window-width)
`w3-right-border')'.
                          -------------------
                     Formatting of hypertext links
                          -------------------
   If the variable `w3-delimit-links' is non-`nil' (the default for
text-terminals), then hypertext links are surrounded by text specified
by the user.  The variables `w3-link-start-delimiter' and
`w3-link-end-delimiter' control what text is at the start and end of a
hypertext link.  These variables are cons-pairs of two strings.
   If a link has never been visited before (it is not in the global
history), then the `car' of these variables is inserted at the start
and end of the link.  If the link has been visited before, then the
`cdr' is inserted.  So, links look like:
     [[This is a hypertext link]] that has never been visited.
     {{This one, however}} has been seen before at some point in time.
   All reserved characters should be replaced with their HTML[+] entity
definitions.
                          -------------------
                          Formatting of lists
                          -------------------
   There are several different ways to control the formatting of lists.
The most obvious is how deeply they are indented relative to the rest of
the paragraphs in the document.  To control this, you should set the
variables `tab-stop-list' and `tab-width'.  A tab every eight spaces is
considered normal, but I prefer to have a tab every four spaces.  So
`tab-stop-list' would be `'(4 8 12 16 20 24 28 32 36 ...)', and
`tab-width' would be `4'.  I use `setq-default' in my `.emacs' for
these, but you can also use them from `w3-mode-hooks'.  Something like:
     (add-hook 'w3-file-prepare-hooks
               (function
                 (lambda ()
                   (setq tab-stop-width (list 4 8 16 20 24 28 32 36 40 44)
                         tab-width 4))))
   Another thing that is easy to change about lists is the bullet
character put at the front of each list item.  This is controlled by
the variable `w3-list-chars-assoc', which is an assoc list.  This is a
list of lists, each sublist describing what to put at the start of each
particular list type.  The `car' of this list should be the type of
list, in all caps (e.g., `UL').  The rest of the list should consist of
strings to insert at certain levels of lists.  The `n'th element of
this list is used when the list is nested `n + 1' levels.  If the list
is not long enough to define a string for a certain nesting level, then
it defaults to either a '*' or a '.'.
                          -------------------
                   Formatting of directory listings
                          -------------------
   When Emacs-w3 encounters a link to a directory (whether by local
file access or via ftp), it can either create an HTML document on the
fly, or use `dired-mode' to peruse the listing.  The variable
`url-use-hypertext-dired' controls this behavior.
   If the value is `t', Emacs-w3 uses `directory-files' to list them
out and transform the directory into a hypertext document, then pass it
through the parser like any other document.
   If the value is `nil', just pass the directory off to dired using
`find-file'.  Using this option loses all the hypertext abilities of
Emacs-w3, and the users is unable to load documents in the directory
directly into Emacs-w3 by clicking with the mouse, etc.
                          -------------------
                   Formatting of gopher directories
                          -------------------
   There are two different ways of viewing gopher links.  You can use
the built-in support that converts gopher directories into HTML, or you
can use the `gopher.el' package by Scott Snyder [e-mail].
The variable that controls this is `w3-use-hypertext-gopher'.  If set
to `nil', then `gopher.el' is used.  Any other value causes Emacs-w3 to
use its internal gopher support.  If you use `gopher.el', you lose all
the hypertext capabilities of Emacs-w3.  All the functionality of
`gopher.el' is now available in the hypertext version, and the
hypertext version supports Gopher+ and ASK blocks.
   The main way to control the display of gopher directories is by the
variable `w3-gopher-labels'.  This variable controls the text that is
inserted at the front of each item.  This is an assoc list of gopher
types (as one character strings), and a string to insert just after the
list item.  All the normal gopher types are defined.  Entries should be
similar to: `("0" . "(TXT)")'.  I have tried to keep all the tags to
three characters plus two parentheses.
                          -------------------
                      Creating a horizontal rule
                          -------------------
   Horizontal rules (<HR> tags in HTML[+]) are used to separate chunks
of a document, and is meant to be rendered as a solid line across the
page.  Some terminals display characters differently, so the variable
`w3-horizontal-rule-char' controls which character is used to draw a
horizontal bar.  This variable must be the ASCII value of the character,
not a string.  The variable is passed through make-string whenever a
horizontal rule of a certain width is necessary.
File: w3,  Node: Character based terminals,  Next: Smart terminals,  Prev: General Formatting,  Up: Controlling Formatting
On character based terminals
============================
   On character based terminals, there is no easy way to show that a
certain range of text is in bold or italics.  If the variable
`w3-delimit-emphasis' is non-`nil', then Emacs-w3 can insert characters
before and after character formatting commands in HTML documents.  The
defaul value of `w3-delimit-emphasis' is automatically set based on the
type of window system and version of Emacs being used.
   Two variables control what text is inserted around different markup
tags.  `w3-header-chars-assoc' controls what characters are inserted
around header items, and `w3-style-chars-assoc' controls what
characters are inserted around most other markup (italics, addresses,
etc.).
   `w3-header-chars-assoc' is an assoc list of header tags and a list
of formatting instructions.  The `car' of the list is the level of the
header (1-6).  The rest of the list should contain three items.  The
first item is text to insert before the header.  The second item is
text to insert after the header.  Both should have reserved characters
converted to their HTML[+] entity definitions.  The third item is a
function to call on the area the header is in.  This function is called
with arguments specifying the start and ending character positions of
the header.  The starting point is always first.  To convert a region to
upper case, please use `w3-upcase-region' instead of `upcase-region',
so that URLs within the region are not corrupted.
   `w3-style-chars-assoc' is an assoc list of style tags and a list of
strings.  The `car' of the list is the type of style tag it specifies
(DFN, B, I, etc.).  The rest of the list should contain two items.  The
`car' is text to insert before the stylized text.  The `cdr' is text to
insert after the stylized text.  Both should have reserved characters
converted to their HTML[+] entity definitions.
File: w3,  Node: Smart terminals,  Next: Graphics workstations,  Prev: Character based terminals,  Up: Controlling Formatting
   If using Emacs 19.2x on a VT100 compatible terminal, Emacs-w3 can
show links, headers, and various other types of emphasis in bold or
underlined text.
   To do this, you should set the variable `w3-emacs19-hack-faces-p' to
non-`nil' in your `~/.emacs' file.  You should also make sure that the
environment variable `TERM' is set to the correct terminal type that
you are using.
   If there is a function called `w3-emacs19-hack-TERMINAL', then this
is used to setup the special characters that turn on bold and
underlined text.  If this function does not exist, you can write one
from scratch, using your terminals entry in the `/etc/termcap' file.
   Each function should use the `standard-display-table' to replace ^A,
^B, ^C, and ^D with escape sequences that turn on highlighting.  When
reading your `/etc/termcap' file, be on the lookout for these codes:
     Code to turn on underlining
     Code to turn off underlining
     Code to turn on boldface type
     Code to turn off all attributes
   Here is an example for creating the VT100 control sequences:
     (defun w3-emacs19-hack-vt100 ()
       "Hack 'faces' for ttys (vt100)"
       (or standard-display-table
           (setq standard-display-table (make-vector 261 nil)))
       (aset standard-display-table 1 (vector (create-glyph "\e[4m")))
       (aset standard-display-table 2 (vector (create-glyph "\e[m")))
       (aset standard-display-table 3 (vector (create-glyph "\e[5m")))
       (aset standard-display-table 4 (vector (create-glyph "\e[m")))
       )
   To turn off the highlighting features, set the variable
`w3-emacs19-hack-faces-p' to `nil' and execute the function
`w3-emacs19-unhack-faces'
   NOTE: This highlighting is not perfect and could cause some odd
display glitches, especially when Emacs does a smart redisplay and
doesn't redraw the whole screen.  `C-l' usually fixes these problems.
File: w3,  Node: Graphics workstations,  Next: Inlined images,  Prev: Smart terminals,  Up: Controlling Formatting
With graphics workstations
==========================
   When you are running in a graphic environemnt (Xwindows or NeXTstep
for example), the fonts and colors used by Emacs-w3 to display text can
be controlled by setting a few resources.  To specify these resources:
   * Xwindows: Place them into your `~/.Xresources' file or the
     `/usr/lib/X11/app-defaults/Emacs' file.
   * NeXTstep: If you are using the NeXTstep port of Emacs 19, you
     should use the `dwrite' command to install these resources.  The
     command should look something like: (`dwrite Emacs
     <Style>.Attribute<item> value', where style and attribute are one
     of the choices below.
   * OS/2 or Windows: If you are using the Lucid Emacs or FSF Emacs
     that has been ported to the Presentation Manager or Windows 3.x,
     it tells you where to store a file that Emacs looks at for
     Xresources.  The resources for each version of Emacs are the same.
For each style of text that Emacs-w3 uses, you can specify any of the
following resources by replacing <style> with the actual style name.
   * Emacs*<Style>.AttributeFont: Font name
   * Emacs*<Style>.AttributeForeground: Foreground color
   * Emacs*<Style>.AttributeBackground: Background color
   * Emacs*<Style>.AttributeUnderline: Underline text?
   Emacs-w3 uses these style names:
`w3-address-style'
     For anything in <ADDRESS> tags.
`w3-bold-style'
     For anything in bold, strong, or a definition
`w3-default-style'
     For normal text
`w3-header-style'
     For any headers
`w3-italic-style'
     For italic text, emphasized, or addresses
`w3-node-style'
     For links to other documents
`w3-strikethru-style'
     For items that should be shown as struck-out.
`w3-subscript-style'
     For subscripted items
`w3-superscript-style'
     For superscripted items
`w3-tt-style'
     For fixed width fonts, code segments, samples, or variables
`w3-underline-style'
     For underlining, and citations
`w3-visited-node-style'
     For displaying hypertext links that have been viewed before
   To determine what styles are displayed in what face, Emacs-w3 uses
an assoc list called `w3-style-assoc'.  It is of the form `(TAGNAME .
FACENAME)', where tagname is the HTML[+] tag that surrounds the text
(without the <, >, or /), and FACENAME is either a symbol representing a
face (in Emacs 19 and Lucid Emacs) or a symbol representing a variable
that holds the face information (Epoch 4.x).
File: w3,  Node: Inlined images,  Prev: Graphics workstations,  Up: Controlling Formatting
   When running in Lucid Emacs 19.10 or XEmacs 19.11, Emacs-w3 can
display inlined images and MPEG movies.  There are several variables
that control how and when the images are displayed.
   Since Lucid/XEmacs only natively understands XPixmaps and XBitmaps,
GIFs and other image types must first be converted to one of these
formats.  To do this, the netpbm utilities(1) programs are normally
used.  This is a suite of freeware image conversion tools.  The
variable `w3-graphic-converter-alist' controls how each image type is
converted.  This is an assoc list, keyed on the MIME content-type.  The
`car' is the content-type, and the `cdr' is a string suitable to pass
to `format'.  A %s in this string will be replaced with a converter
from the ppm image format to an XPixmap (or XBitmap, if being run on a
monochrome display).  By default, the emacs-w3 browser has converters
  1. image/x-xbitmap
  2. image/xbitmap
  3. image/xbm
  4. image/gif
  5. image/x-fax
  6. image/x-raster
  7. image/windowdump
  8. image/x-icon
  9. image/portable-graymap
 10. image/portable-pixmap
 11. image/x-pixmap
 12. image/x-xpixmap
 13. image/pict
 14. image/x-macpaint
 15. image/x-targa
 16. image/tiff
   Since most displays are not 24-bit, Emacs-w3 can automatically
dither an image, so that it does not fill up the application' colormap
too quickly.  If `w3-color-use-reducing' is non-`nil', then the images
will use reduced colors.  If `w3-color-filter' is `eq' to `'ppmquant',
then the ppmquant program will be used.  If `eq' to `'ppmdither', then
the ppmdither program will be used.  The ppmdither program tends to
give better results.  The values of `w3-color-max-red',
`w3-color-max-blue', and `w3-color-max-green' control how many colors
the inlined images can use.  If using ppmquant, then the product of
these three variables is used as the maximum number of colors per
image.  If using ppmdither, then only the set number of color cells can
be allocated per image.  See the man pages for ppmdither and ppmquant
for more information on how the dithering is actually done.
   :: WORK ::
   w3-delay-image-loads w3-delay-mpeg-loads
   w3-load-delayed-images w3-load-delayed-mpegs
   w3-graphics-entities-alist w3-graphics-always-show-entities
   ---------- Footnotes ----------
   (1)  Available via anonymous ftp from
ftp.x.org:/R5contrib/netpbm-1mar1994.tar.gz, and most large ftp sites.
File: w3,  Node: HTTP/1.0 Support,  Next: Redirection,  Prev: Top,  Up: Top
HTTP/1.0 Support
****************
   The new revision of the HTTP specification adds much more
functionality to the server side of a transaction.  Access
authorization has been added, and several types of redirection can
occur.  All of this negotiation and redirection should take place
before the user ever sees the first requested page--this avoids the
overhead of parsing any error messages or old documents the server may
have returned with the redirection or authorization message.  The new
protocol is also MIME (Multimedia Internet Mail Extensions, see RFC
1341) compliant.
* Menu:
* Redirection::
* Authentication::                      Accessing restricted servers and
                                        documents
* Payment::                             How to pay for services over the
                                        World Wide Web
* MIME Support::                        How Emacs-w3 uses MIME types, and how to
                                        modify its behavior.
File: w3,  Node: Redirection,  Next: Authentication,  Prev: HTTP/1.0 Support,  Up: HTTP/1.0 Support
Redirection
===========
   One of the most useful aspects of HTTP/1.0 is the ability to
transparently move files between different servers (perhaps even
different protocols).  Most of the WWW browsers support redirection in
some form or another.  The Emacs browser supports all three types of
redirection in the HTTP/1.0 specification (error codes 301, 302, and
303).
   Whenever a redirection response is detected, the URL specified by the
Location: header is retrieved.  All relative references are resolved
before requesting the new URL.
   Eventually, an HTML editor that is tightly integrated with the
browser is planned, and will include the ability to edit documents to
change their links if a permanent relocation is seen.
File: w3,  Node: Authentication,  Next: Payment,  Prev: Redirection,  Up: HTTP/1.0 Support
Authentication
==============
   Lots of information is useful to a group of people within an
organization, or a group working on a project, but it is not always wise
to distribute this information to the world at large.
   The HTTP/1.0 protocol adds the capability to have authentication
based on usernames and passwords.  If the improper username/password
pair is sent to the server, an error code of 401, Unauthorized is
returned by the server.
   The browser has a very extensible interface to its authentication
handling.  When a 401 error code is received, the Auth-type header is
checked--this header field should be a space-separated list of suitable
authorization schemes for the requested URL.  The value of this header
is read into a lisp symbol by way of Emacs's read-string function.
This lisp symbol looks like `url-authtype-auth', where authtype is
replaced by the correct authorization type.  The authorization types
defined in the latest HTTP/1.0 specification include user, basic,
public key, and kerberos (versions 4 and 5).  If a function of this
name is currently defined, then the function is called via `funcall'
with several parameters:
  1. The URL being authenticated.
  2. whether to prompt for a username/password if no cached data is
     found.
  3. whether to overwrite an old username/password if the information is
     found in the cache.
        This interface was chosen for its flexibility and
extensibility.  The main routine that does the MIME parsing and the
buil,ding of the Authorization header does not need to know how to
handle each type of authentication, and the addition of a new method
for authentication is simply a matter of defining one function that
conforms to a simple interface.
   The only authorization supported by the browser at this time is
'basic.' This is simply a string that looks like `user:password' that
has been encoded using Base64 encoding as defined in RFC 1421.  It is
given as an example of how to write an authorization module.  All of the
functions for storing, retrieving, and over-writing the cached
authorization information should all be handled by one function
(although it would be perfectly acceptable to have a stub function that
passed off to three larger functions based on its parameters).  The most
efficient way to store the cached information is by an assoc-list of
assoc-lists.  The top level assoc list is keyed on the name of the
server.  The secondary assoc-list is keyed on the full path of the file
that is protected.  Thus, a sample authorization cache would look like
this:
     ((``info.cern.ch''    . ((``/foo''        . ``d21wZXJyeTp0ZXN0aW5n'')
                              (``/bar''        . ``amtvbnJhdGg6ZGlzbWVtYmVy'')
                              (``/foo/x.html'' . ``dmlvbGV0dDpvcGVuZ2w='')))
      (``cs.indiana.edu''  . ((``/elisp/w3/''  . ``dGxvb3M6Y29ucXVlcg=='')
                              (``/''           . ``bXZhbmhleW46a2lsbGh1bGljaw=='')))
     )
   The structure consists of two assoc-lists for the sake of speed.  The
list of cached information could conceivably hold several thousand links
(if the user does not exit Emacs for long periods of time.)  If the list
were keyed on a full URL, the assoc function would have to search
through every link before failing to find a new URL.  With the current
scheme, assoc only has to search though a few items (maximum is the
number of HTTP servers, which should always be much, much smaller than
the number of distinct URLs.)  Even with a 3:1 ratio of URLs to each
server, this is a big win.
File: w3,  Node: Payment,  Next: MIME Support,  Prev: Authentication,  Up: HTTP/1.0 Support
Payment
=======
   The Chargeto: header will be used to pay for services offered over
the World Wide Web.  Such things as electronic magazines and commercial
databases all need a way to restrict access to only authorized
subscribers.  The format of the header has yet to be specified, but the
interface and storage techniques will be similar to the Authorization
section.
File: w3,  Node: MIME Support,  Next: Adding MIME types based on file extensions,  Prev: Payment,  Up: HTTP/1.0 Support
MIME Support
============
   MIME is an emerging standard for multimedia mail.  It offers a very
flexible typing mechanism.  The type of a file/message is specified in
two parts, separated by a '/'.  The first part is a general category of
data (text, application, image, etc.).  The second part is the specific
type of data (postscript, gif, jpeg, etc.).  So `text/html' specifies
an HTML document, whereas `image/x-xwindowdump' specifies an image of
an Xwindow taken with the xwd program.
   This typing allows much more flexibility in naming files.  HTTP/1.0
servers can now send back content-type headers in response to a request,
and not have the client second-guess it based on file extensions.  Now
you can name HTML files `something.gif' if you really felt like it (not
a great idea, but doable).
* Menu:
* Adding MIME types based on file extensions::  How to map file
                                                extensions onto MIME
                                                types (e.g., `.gif ->
                                                image/gif)'.
* Mapping gopher types to MIME types::          Going from gopher typing
                                                to MIME types.
* Specifying Viewers::  How to specify external and internal viewers
                        for files that Emacs-w3 cannot handle natively.
* Mailcap File::        How to set up and use a Mailcap file.  Standard
                        way to specify MIME viewers - compatible with
                        Mosaic and most MIME compliant mailers.
File: w3,  Node: Adding MIME types based on file extensions,  Next: Mapping gopher types to MIME types,  Prev: MIME Support,  Up: MIME Support
Adding MIME types based on file extensions
------------------------------------------
   For some protocols however, it is still necessary to guess the
content of a file based on the file extension.  This type of guess-work
should only be needed when accessing files via FTP, local file access,
or old HTTP/0.9 servers.
   Instead of specifying how to view things twice, once based on
content-type and once based on the file extension, it is easier to map
file extensions to MIME content-types.  The variable that controls this
is `mm-mime-extensions'.
   This variable is an assoc list of file extensions and the
corresponding MIME content-type.  A sample entry looks like: `(".movie"
. "video/x-sgi-movie")' This makes all files that end in `.movie'
(`foo.movie' and `bar.movie') be interpreted as SGI animation files.
If a content-type is defined for the document, then this is
over-ridden.  Regular expressions can NOT be used.
   Both Mosaic and the NCSA HTTP daemon rely on a separate file for
mapping file extensions to MIME types.  Instead of having the users of
Emacs-w3 duplicate this in lisp, this file can be parsed using the
`url-parse-mimetypes' function.  This function is called each time w3
is loaded.  It tries to locate mimetype files in several places. If the
environment variable `MIMETYPES' is nonempty, then this is assumed to
specify a UNIX-like path of mimetype files (this is a colon separated
string of pathnames).  If the `MIMETYPES' environment variable is
empty, then Emacs-w3 looks for these files:
  1. `~/.mime-types'
  2. `/etc/mime-types'
  3. `/usr/etc/mime-types'
  4. `/usr/local/etc/mime-types'
  5. `/usr/local/www/conf/mime-types'
   Each line contains information for one http type.  These types
resemble MIME types.  If you plan to add new ones, you should use
subtypes beginning with x-, such as application/x-myprogram.  Lines
beginning with # are comment lines, and suitably ignored.  Each line
consists of:
   type/subtype ext1 ext2 ...  extN
   type/subtype is the MIME-like type of the document. ext* is any
number of space-separated filename extensions which correspond to the
MIME type.
File: w3,  Node: Mapping gopher types to MIME types,  Next: Specifying Viewers,  Prev: Adding MIME types based on file extensions,  Up: MIME Support
Mapping gopher types to MIME types
----------------------------------
   Need to fill this in :: WORK ::
File: w3,  Node: Specifying Viewers,  Next: Mailcap File,  Prev: Mapping gopher types to MIME types,  Up: MIME Support
Specifying Viewers
------------------
   Not all files look as they should when parsed as an HTML document
(whitespace is stripped, paragraphs are reformatted, and lots of little
changes that make the document look unrecognizable).  Files may be
passed to external programs or Emacs Lisp functions to be viewed.
   Not all files can be viewed accurately from within an Emacs session
(GIF files for example, or audio files).  For this reason, the user can
specify file "viewers" based on MIME content-types.  The variable
`w3-mime-viewers' is an assoc-list contains MIME content-types and a
lisp object specifying how to view a document.
   If the lisp object is a string (e.g., `"xv -perfect %s"'), it
specifies an external program that should be used to view the document.
This is passed through the `format' function.  The first %s is replaced
with the temporary file name the retrieved document is saved in, and
then that resulting string is used as a command in a subprocess via
`start-process'.
   If the lisp object is a lisp symbol (e.g., `tar-mode'), it species a
lisp function to call after visiting the buffer.  This is appropriate
for using major modes to view documents.  The function is called with no
arguments.
   If the lisp object is a list (e.g., `(message "wow")'), it specifies
something to be passed through `eval'.
File: w3,  Node: Mailcap File,  Prev: Specifying Viewers,  Up: MIME Support
Mailcap File
============
   NCSA Mosaic and almost all other WWW browsers rely on a separate file
for mapping MIME types to external viewing programs.  This takes some of
the burden off of browser developers, so each browser does not have to
support all image formats, or postscript, etc.  Instead of having the
users of Emacs-w3 duplicate this in lisp, this file can be parsed using
the `mm-parse-mailcaps' function.  This function is called each time w3
is loaded.  It tries to locate mimetype files in several places. If the
environment variable `MAILCAPS' is nonempty, then this is assumed to
specify a UNIX-like path of mimetype files (this is a colon separated
string of pathnames).  If the `MAILCAPS' environment variable is empty,
then Emacs-w3 looks for these files:
  1. `~/.mailcap'
  2. `/etc/mailcap'
  3. `/usr/etc/mailcap'
  4. `/usr/local/etc/mailcap'
   This format of this file is specified in RFC 1343, but a brief
synopsis follows (this is taken verbatim from sections of RFC 1343).
   Each mailcap file consists of a set of entries that describe the
proper handling of one media type at the local site.  For example, one
line might tell how to display a message in Group III fax format.  A
mailcap file consists of a sequence of such individual entries,
separated by newlines (according to the operating system's newline
conventions). Blank lines and lines that start with the "#" character
(ASCII 35) are considered comments, and are ignored.  Long entries may
be continued on multiple lines if each non-terminal line ends with a
backslash character ('\', ASCII 92), in which case the multiple lines
are to be treated as a single mailcap entry.  Note that for such
"continued" lines, the backslash must be the last character on the line
to be continued.
   Each mailcap entry consists of a number of fields, separated by
semi-colons.  The first two fields are required, and must occur in the
specified order.  The remaining fields are optional, and may appear in
any order.
   The first field is the content-type, which indicates the type of data
this mailcap entry describes how to handle.  It is to be matched against
the type/subtype specification in the "Content-Type" header field of an
Internet mail message.  If the subtype is specified as "*", it is
intended to match all subtypes of the named content-type.
   The second field, view-command, is a specification of how the
message or body part can be viewed at the local site.  Although the
syntax of this field is fully specified, the semantics of program
execution are necessarily somewhat operating system dependent.
   The optional fields, which may be given in any order, are as follows:
   * The "compose" field may be used to specify a program that can be
     used to compose a new body or body part in the given format.  Its
     intended use is to support mail composing agents that support the
     composition of multiple types of mail using external composing
     agents.  As with the view- command, the semantics of program
     execution are operating system dependent.  The result of the
     composing program may be data that is not yet suitable for mail
     transport--that is, a Content-Transfer-Encoding may need to be
     applied to the data.
   * The "composetyped" field is similar to the "compose" field, but is
     to be used when the composing program needs to specify the
     Content-type header field to be applied to the composed data.  The
     "compose" field is simpler, and is preferred for use with existing
     (non-mail-oriented) programs for composing data in a given format.
     The "composetyped" field is necessary when the Content-type
     information must include auxilliary parameters, and the
     composition program must then know enough about mail formats to
     produce output that includes the mail type information.
   * The "edit" field may be used to specify a program that can be used
     to edit a body or body part in the given format.  In many cases,
     it may be identical in content to the "compose" field, and shares
     the operating-system dependent semantics for program execution.
   * The "print" field may be used to specify a program that can be
     used to print a message or body part in the given format.  As with
     the view-command, the semantics of program execution are operating
     system dependent.
   * The "test" field may be used to test some external condition (e.g.
     the machine architecture, or the window system in use) to
     determine whether or not the mailcap line applies.  It specifies a
     program to be run to test some condition.  The semantics of
     execution and of the value returned by the test program are
     operating system dependent.  If the test fails, a subsequent
     mailcap entry should be sought.  Multiple test fields are not
     permitted--since a test can call a program, it can already be
     arbitrarily complex.
   * The "needsterminal" field indicates that the view-command must be
     run on an interactive terminal.  This is needed to inform
     window-oriented user agents that an interactive terminal is
     needed.  (The decision is not left exclusively to the view-command
     because in some circumstances it may not be possible for such
     programs to tell whether or not they are on interactive
     terminals.)  The needsterminal command should be assumed to apply
     to the compose and edit commands, too, if they exist.  Note that
     this is NOT a test--it is a requirement for the environment in
     which the program will be executed, and should typically cause the
     creation of a terminal window when not executed on either a real
     terminal or a terminal window.
   * The "copiousoutput" field indicates that the output from the
     view-command will be an extended stream of output, and is to be
     interpreted as advice to the UA (User Agent mail- reading program)
     that the output should be either paged or made scrollable. Note
     that it is probably a mistake if needsterminal and copiousoutput
     are both specified.
   * The "description" field simply provides a textual description,
     optionally quoted, that describes the type of data, to be used
     optionally by mail readers that wish to describe the data before
     offering to display it.
   * The "x11-bitmap" field names a file, in X11 bitmap (xbm) format,
     which points to an appropriate icon to be used to visually denote
     the presence of this kind of data.
   * Any other fields beginning with "x-" may be included for local or
     mailer-specific extensions of this format.  Implementations should
     simply ignore all such unrecognized fields to permit such
     extensions, some of which might be standardized in a future
     version of this document.
File: w3,  Node: Advanced Features,  Next: Searching,  Up: Top
Advanced Features
*****************
* Menu:
* Searching::        How to search entire sections of the web
            for what you want, automatically.
* Interfacing to VM::    How to make VM understand hypertext links
* Interfacing to RMAIL::How to make RMAIL understand hypertext links
* Interfacing to GNUS::    How to make GNUS understand hypertext links
* Using PGP/PEM::    How to use various public-key crypto-systems
            to ensure the security of your HTTP
                        transactions.
* Native WAIS Support:: How to make Emacs-w3 understand WAIS links without
                        using a gateway.
* Rating Links::        How to make Emacs-w3 put an 'interestingness' value
                        next to each link.
* Gopher Plus Support:: How Emacs-w3 makes use of the Gopher+ protocol.
* Hooks::               Various hooks to use throughout Emacs-w3
* Other Variables::     Miscellaneous variables that control the real
                        guts of Emacs-w3.
File: w3,  Node: Searching,  Next: Interfacing to VM,  Prev: Advanced Features,  Up: Advanced Features
Searching
=========
   In the file `w3-search.el' is a function that some of you may find
handy.  It is not 100% completed yet, so if you run into any problems
with it, please try to fix it, not just say its broken.
   The function is `w3-do-search'.  It must be called with at least one
argument.  All others are optional.  Arguments are TERM, BASE,
HOPE-LIMIT, and RESTRICTION.  This recursively descends all the child
links of the current document for TERM.  TERM may be a string, in which
case it is treated as a regular expression, and `re-search-forward' is
used, or a symbol, in which case it is funcalled with 1 argument, the
current URL being searched.
   BASE is the URL to start searching from.
   HOPS-LIMIT is the maximum number of nodes to descend before the
search dies out.
   RESTRICTION is a regular expression or function to call with one
argument, a URL that could be searched.  If RESTRICTION returns
non-`nil', then the URL is added to the queue, otherwise it is
discarded.  This is useful for restricting searching to either certain
types of URLs (only search ftp links), or restricting searching to one
domain (only search stuff in the indiana.edu domain).
   You may check several variables from the main `w3-do-search' routine
in any functions passed to it (as RESTRICTION or TERM). QUEUE is the
queue of links to be searched, HOPS is the current number of hops from
the root document, RESULTS is an assoc list of (URL . RETVAL), where
RETVAL is the value returned from previous calls to the TERM function
(or point if searching for a regular expression).
   The function returns a list of the form: ((URL . RETVAL)...)
   Please note that there is no interactive use for this function
yet--it was designed for non-interactive, batch-mode processing.
However, if anyone wants to write a wrapper function for it, please feel
free.
File: w3,  Node: Interfacing to VM,  Next: Interfacing to RMAIL,  Prev: Searching,  Up: Advanced Features
Interfacing to VM
=================
   More and more people are including URLs in their signatures, and
within the body of mail messages.  It can get quite tedious to type
these into the minibuffer when you wish to follow one.  The following
functions in your `~/.emacs' or `~/.vm' files should do the trick.  It
adds two keybindings to the main VM message window.  The middle mouse
button now tries to follow a hypertext link.  This first tries to find
any links that were fully-qualified with the HTML <A> and </A> (1) tags,
otherwise it checks to see if the text around point is a naked URL (2).
`w3-build-links-list' should not be run on a VM or RMAIL buffer, since
it will modify the buffer contents (and therefore the actual mail
message), and there is no way to revert the message short of reverting
the entire mail folder.
     (defun w3-maybe-follow-link-mouse (e)
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive "e")
       (save-excursion
         (mouse-set-point e)
         (w3-maybe-follow-link)))

     (defun w3-maybe-follow-link ()
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive)
       (require 'w3)
       (if (not w3-setup-done) (w3-do-setup))
       (let* ((zn  (w3-zone-at (point)))
              (url1 (and zn (w3-zone-data zn)))
              (url2 (url-get-url-at-point)))
         (cond
           (url1 (w3-follow-link))
           ((and url2 (string-match url-nonrelative-link url2)) (w3-fetch url2))
           (t (message "w3-maybe-follow-link got confused.")))))

     (add-hook 'vm-mode-hook
               (function
                 (lambda ()
                   (define-key vm-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
                   (define-key vm-mode-map "\r"      'w3-maybe-follow-link))))
   ---------- Footnotes ----------
   (1)  Something akin to <a href="http://cs.indiana.edu/">
   (2)  Similar to http://cs.indiana.edu/
File: w3,  Node: Interfacing to RMAIL,  Next: Interfacing to GNUS,  Prev: Interfacing to VM,  Up: Advanced Features
Interfacing to RMAIL
====================
   More and more people are including URLs in their signatures, and
within the body of mail messages.  It can get quite tedious to type
these into the minibuffer when you wish to follow one.  The following
functions in your `~/.emacs' files should do the trick.  It adds two
keybindings to the main RMAIL window.  The middle mouse button now
tries to follow a hypertext link.  This first tries to find any links
that were fully-qualified with the HTML <A> and </A> (1) tags,
otherwise it checks to see if the text around point is a naked URL (2).
`w3-build-links-list' should not be run on a VM or RMAIL buffer, since
it will modify the buffer contents (and therefore the actual mail
message), and there is no way to revert the message short of reverting
the entire mail folder.
     (defun w3-maybe-follow-link-mouse (e)
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive "e")
       (save-excursion
         (mouse-set-point e)
         (w3-maybe-follow-link)))

     (defun w3-maybe-follow-link ()
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive)
       (require 'w3)
       (if (not w3-setup-done) (w3-do-setup))
       (let* ((zn  (w3-zone-at (point)))
              (url1 (and zn (w3-zone-data zn)))
              (url2 (url-get-url-at-point)))
         (cond
           (url1 (w3-follow-link))
           ((and url2 (string-match url-nonrelative-link url2)) (w3-fetch url2))
           (t (message "w3-maybe-follow-link got confused.")))))

     (add-hook 'rmail-mode-hook
           (function
            (lambda ()
              (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
              (define-key rmail-mode-map "\r"      'w3-maybe-follow-link))))
   ---------- Footnotes ----------
   (1)  Something akin to <a href="http://cs.indiana.edu/">
   (2)  Similar to http://cs.indiana.edu/
File: w3,  Node: Interfacing to GNUS,  Next: Using PGP/PEM,  Prev: Interfacing to RMAIL,  Up: Advanced Features
Interfacing to GNUS
===================
   More and more people are including URLs in their signatures and
within the body of usenet posts.  It can get quite tedious to type
these into the minibuffer when you wish to follow one.  The following
functions in your `~/.emacs' file should do the trick.  It adds two
keybindings to the GNUS article buffer.  The middle mouse button tries
to follow a hypertext link.  This first tries to find any links that
were fully-qualified with the HTML <A> and </A> (1) tags, otherwise it
checks to see if the text around point is a naked URL (2).
     (defun w3-maybe-follow-link-mouse (e)
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive "e")
       (save-excursion
         (mouse-set-point e)
         (w3-maybe-follow-link)))

     (defun w3-maybe-follow-link ()
       "Maybe follow a hypertext link under point.
     If there is no link under point, this will try using
     url-get-url-at-point"
       (interactive)
       (require 'w3)
       (if (not w3-setup-done) (w3-do-setup))
       (let* ((zn  (w3-zone-at (point)))
              (url1 (and zn (w3-zone-data zn)))
              (url2 (url-get-url-at-point)))
         (cond
           (url1 (w3-follow-link))
           ((and url2 (string-match url-nonrelative-link url2)) (w3-fetch url2))
           (t (message "w3-maybe-follow-link got confused.")))))

     (add-hook 'gnus-article-mode-hook
               (function
                 (lambda ()
                   (define-key gnus-article-mode-map [mouse-2]
                               'w3-maybe-follow-link-mouse)
                   (define-key gnus-article-mode-map "\r"
                               'w3-maybe-follow-link))))

     (add-hook 'gnus-article-prepare-hook
               (function
                 (lambda ()
                   (let ((w3-working-buffer gnus-article-buffer))
                     (w3-build-links-list)))))
   ---------- Footnotes ----------
   (1)  Something akin to <a href="http://cs.indiana.edu/">
   (2)  Similar to http://cs.indiana.edu/